@starci/hfs 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.6.0 - 2026-10-18
+- Added: `services.codecov|sonar.badgeToken` README badge tokens and `ci.github.visibility` with a private-repository notice (sync, ci verify); `ci.vars` `ownerValue: true` (var sync skips, var set reads stdin, verify checks the name).
+- Fixed: the app release gate counts tag-push CI runs reachable from origin/main, main or HEAD; the secret scans exempt only declared badge tokens.
+- Fixed: empty placeholder lines vanish so every managed file is prettier-stable; CI coverage proof heap, per-side Sonar lint reports merged for the import, per-fe-app build env; `app lint --side` combines with `--sonar`.
+
+## 4.5.1 - 2026-10-18
+- Fixed: managed CI base refs, public build values, caching and timeouts; optional quality service handling, README formatting and Supabase migration-history parsing.
+
 ## 4.5.0 - 2026-10-17
 - Added: consumer-class CI declarations, `app ci` custody verbs and R296-R298; manifest-driven quality files and split cached CI with immutable action pins.
 - Added: release audit/local Sonar and main-CI protection; encrypted outside-repository DB dump and armed linked reset with backup/auth/storage validation.

package/ci/cli.mjs

@@ -5,7 +5,7 @@ import { readCiDeclaration, sealedKeyNames } from '../runtime/scripts/hfs/ci-dec
 import { github, refuse } from './github.mjs';
 import { setSecret } from './secret.mjs';
 import { setVariable, syncVariables } from './vars.mjs';
-import { verifyCi } from './verify.mjs';
+import { badgeVisibilityNotices, verifyCi } from './verify.mjs';
 
 const COMMANDS = {
   'secret set': ['env', 'dependabot', 'repo'],
@@ -46,16 +46,18 @@ function parse(argv) {
 export async function ciMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), stdin, env = process.env, tools = {} } = {}) {
   try {
     const parsed = parse(argv);
-    let declaration, sealed;
+    let doc, declaration, sealed;
     try {
-      declaration = readCiDeclaration(parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8')));
+      doc = parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8'));
+      declaration = readCiDeclaration(doc);
       sealed = sealedKeyNames(cwd, { fs });
     } catch { throw refuse('CI_DECLARATION_INVALID', 'the manifest or sealed key names could not be read'); }
     if (declaration.problems.length) throw refuse('CI_DECLARATION_INVALID', 'correct the CI declaration before using GitHub');
     const context = { ...parsed, declaration, sealed, gh: github({ cwd, env, spawn: tools.spawn }), stdin, stdout };
     if (parsed.command === 'secret set') return await setSecret(context);
-    if (parsed.command === 'var set') return setVariable(context);
+    if (parsed.command === 'var set') return await setVariable(context);
     if (parsed.command === 'var sync') return syncVariables(context);
+    context.notices = badgeVisibilityNotices({ doc, gh: context.gh, repo: context.gh.repository(parsed.options.repo) });
     return verifyCi(context);
   } catch (error) {
     stderr(`${error.code ? error.message : 'CI_USAGE: CI command could not complete'}\n`);

package/ci/vars.mjs

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
 import { declaredEntry } from './secret.mjs';
 
@@ -15,18 +16,34 @@ function writeVariable(gh, repo, entry, value, options, stdout) {
   stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
 }
 
-export function setVariable({ declaration, gh, options, name, stdout }) {
-  const entry = declaredEntry(declaration.vars, name, options), value = valueOf(entry, options.value);
+/** Owner-supplied input is read once from stdin, with one trailing newline removed and no value echoed. */
+async function ownerValueOf(options, stdin) {
+  if (Object.hasOwn(options, 'value')) throw refuse('CI_VALUE_ARGV', 'an owner-supplied variable takes its value on stdin');
+  let value;
+  if (stdin === undefined) {
+    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+    value = fs.readFileSync(0, 'utf8');
+  } else value = typeof stdin === 'function' ? await stdin() : stdin;
+  value = String(value ?? '').replace(/\r?\n$/, '');
+  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+  return value;
+}
+
+/** Owner-supplied variables accept stdin only; other public variables retain manifest and argv agreement. */
+export async function setVariable({ declaration, gh, options, name, stdin, stdout }) {
+  const entry = declaredEntry(declaration.vars, name, options);
+  const value = entry.ownerValue ? await ownerValueOf(options, stdin) : valueOf(entry, options.value);
   writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
   return 0;
 }
 
 /** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
 export function syncVariables({ declaration, gh, options, stdout }) {
-  const plan = declaration.vars.map((entry) => ({ entry, value: valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
-  const repo = options.execute && plan.length ? gh.repository(options.repo) : undefined;
+  const plan = declaration.vars.map((entry) => ({ entry, value: entry.ownerValue ? undefined : valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
+  const repo = options.execute && plan.some((item) => !item.entry.ownerValue) ? gh.repository(options.repo) : undefined;
   for (const item of plan) {
-    if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
+    if (item.entry.ownerValue) stdout(`skip variable ${item.entry.name} (${scopeName(item.options)}): owner-supplied value; the owner runs starci app ci var set ${item.entry.name} [--env ENV] with the value on stdin\n`);
+    else if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
     else stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
   }
   return 0;

package/ci/verify.mjs

@@ -1,7 +1,8 @@
+import { badgeTokenNotices } from '../sync/readme-badges.mjs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
 
 /** Verification reports names and scopes only; values are compared in memory and excluded from findings. */
-export function verifyCi({ declaration, sealed, gh, options, stdout }) {
+export function verifyCi({ declaration, sealed, gh, options, stdout, notices = [] }) {
   const repo = gh.repository(options.repo), stores = [];
   const environments = [...new Set([...declaration.secrets, ...declaration.vars].filter((item) => item.scope === 'environment').map((item) => item.environment))].sort();
   for (const scope of [{}, ...environments.map((env) => ({ env })), { dependabot: true }]) {
@@ -29,8 +30,21 @@ export function verifyCi({ declaration, sealed, gh, options, stdout }) {
       add(sameKind.some((entry) => entry.name === row.name) ? 'CI_SCOPE_MISMATCH' : store.kind === 'secret' ? 'CI_SECRET_UNDECLARED' : 'CI_VAR_UNDECLARED', row.name, store.scope);
     }
   }
-  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings }, null, 2)}\n`);
+  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings, notices }, null, 2)}\n`);
   else if (!findings.length) stdout('CI verification passed\n');
   else for (const finding of findings) stdout(`${finding.code}: ${finding.name} (${finding.scope})\n`);
+  if (!options.json) for (const notice of notices) stdout(`${notice}\n`);
   return findings.length ? 1 : 0;
 }
+
+/** Manifest visibility wins; optional GitHub visibility discovery never changes verification findings or errors. */
+export function badgeVisibilityNotices({ doc, gh, repo }) {
+  let visibility = doc?.ci?.github?.visibility;
+  if (visibility === undefined) {
+    try {
+      const remote = gh.json(['repo', 'view', '--json', 'visibility', '--repo', repo]);
+      visibility = ['PRIVATE', 'INTERNAL'].includes(remote?.visibility) ? 'private' : 'public';
+    } catch { return []; }
+  }
+  return badgeTokenNotices({ ...doc, ci: { ...doc?.ci, github: { ...doc?.ci?.github, visibility } } }, { repository: `https://github.com/${repo}` });
+}

package/lint/run.mjs

@@ -26,7 +26,7 @@ import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 
-// --side judges only that side; root HFS findings belong to be, and Sonar always requires the full lint.
+// --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
 const STYLE_SIDE = 'fe';
@@ -42,11 +42,10 @@ export function workspaceOf(workspace) {
   return rel;
 }
 
-/** Side scopes partition the full lint; Sonar requires the complete report and a frontend workspace cannot belong to be. */
+/** Side scopes partition the full lint; Sonar reports share that scope and a frontend workspace cannot belong to be. */
 function validateSide(opts) {
   if (opts.side === undefined) return;
   if (!SIDES.includes(opts.side)) throw new Error('LINT_SIDE_INVALID: --side is be or fe');
-  if (opts.sonar !== undefined) throw new Error('LINT_SIDE_SONAR_CONFLICT: --side and --sonar do not combine');
   if (opts.side === 'be' && opts.workspace !== undefined) throw new Error('LINT_SIDE_WORKSPACE_CONFLICT: --side be cannot judge a frontend workspace');
 }
 
@@ -312,7 +311,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
 
   let properties = '';
   try { properties = fs.readFileSync(path.join(repoRoot, 'sonar-project.properties'), 'utf8'); } catch { /* no properties: every finding keeps its own path */ }
-  const sourceRoots = sourceRootsOf(properties);
+  const sourceRoots = sourceRootsOf(properties).filter((root) => findingOnSide({ path: root }, opts.side));
   const tracked = sourceRoots.length ? trackedFiles(repoRoot) : [];
   const sonar = mergeReports([
     sonarReport(kept, { sourceRoots, tracked }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/ci-red.mjs

@@ -20,29 +20,61 @@ function runsOf(result) {
   } catch { return null; }
 }
 
+/** Resolve each available default-branch reference once, including HEAD in detached release worktrees. */
+function referenceTips(spawn, cwd, defaultBranch) {
+  const refs = [`origin/${defaultBranch}`, defaultBranch, 'HEAD'];
+  return refs.flatMap((name) => {
+    const result = run(spawn, cwd, 'git', ['rev-parse', '--verify', '--quiet', `${name}^{commit}`]);
+    const tip = String(result.stdout ?? '').trim();
+    return !result.error && result.status === 0 && SHA.test(tip) ? [{ name, tip }] : [];
+  });
+}
+
+/** Equality proves reachability directly; ancestry is unknown only when every available probe errors. */
+function pushAncestry(spawn, cwd, row, refs) {
+  if (refs.some((ref) => ref.tip === row.headSha)) return { candidate: true, unknown: false };
+  let known = false;
+  for (const ref of refs) {
+    const result = run(spawn, cwd, 'git', ['merge-base', '--is-ancestor', row.headSha, ref.tip]);
+    if (!result.error && result.status === 0) return { candidate: true, unknown: false };
+    if (!result.error && result.status === 1) known = true;
+  }
+  return { candidate: false, unknown: !known };
+}
+
+/** Branch rows remain candidates; push rows must reach a resolved reference, and each databaseId counts once. */
+function candidateRuns(spawn, cwd, branch, pushes, refs) {
+  const candidates = branch.filter((row) => row && SHA.test(row.headSha));
+  let ancestryUnknown = refs.length === 0;
+  for (const row of pushes) {
+    if (!row || !SHA.test(row.headSha) || row.event !== 'push') continue;
+    const ancestry = pushAncestry(spawn, cwd, row, refs);
+    if (ancestry.candidate) candidates.push(row);
+    if (ancestry.unknown) ancestryUnknown = true;
+  }
+  const unique = new Map();
+  for (const row of candidates) if (!unique.has(row.databaseId)) unique.set(row.databaseId, row);
+  return { candidates: [...unique.values()], ancestryUnknown };
+}
+
 /** Reads branch runs plus push/tag runs whose commits are reachable from the default branch; the newest completed run decides, even if a newer run is pending. */
 export function latestDefaultBranchCi({ spawn, cwd, defaultBranch = 'main' }) {
+  const refs = referenceTips(spawn, cwd, defaultBranch);
+  const unknown = (why) => ({ state: 'unknown', why: `${why} (refs: ${refs.map((ref) => ref.name).join(', ') || 'none'})` });
   const args = ['run', 'list', '--workflow', 'ci.yml'];
   const tail = ['--limit', '20', '--json', FIELDS];
   const branch = runsOf(run(spawn, cwd, 'gh', [...args, '--branch', defaultBranch, ...tail]));
-  if (!branch) return { state: 'unknown', why: 'gh branch runs unavailable (missing gh, authentication, or unreadable response)' };
+  if (!branch) return unknown('gh branch runs unavailable (missing gh, authentication, or unreadable response)');
   const pushes = runsOf(run(spawn, cwd, 'gh', [...args, '--event', 'push', ...tail]));
-  if (!pushes) return { state: 'unknown', why: 'gh push runs unavailable (missing gh, authentication, or unreadable response)' };
-  const candidates = branch.filter((row) => row && SHA.test(row.headSha));
-  let ancestryUnknown = false;
-  for (const row of pushes) {
-    if (!row || !SHA.test(row.headSha) || row.event !== 'push') continue;
-    const ancestor = run(spawn, cwd, 'git', ['merge-base', '--is-ancestor', row.headSha, defaultBranch]);
-    if (!ancestor.error && ancestor.status === 0) candidates.push(row);
-    else if (ancestor.error || ancestor.status !== 1) ancestryUnknown = true;
-  }
+  if (!pushes) return unknown('gh push runs unavailable (missing gh, authentication, or unreadable response)');
+  const { candidates, ancestryUnknown } = candidateRuns(spawn, cwd, branch, pushes, refs);
   const completed = candidates.filter((row) => row.status === 'completed' && Number.isFinite(Date.parse(row.createdAt)));
   completed.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || Number(b.databaseId) - Number(a.databaseId));
   const latest = completed[0];
-  if (!latest) return { state: 'unknown', why: ancestryUnknown ? 'cannot establish push run ancestry on the default branch' : 'no completed CI run on the default branch' };
+  if (!latest) return unknown(ancestryUnknown ? 'cannot establish push run ancestry on the default branch' : 'no completed CI run on the default branch');
   if (latest.conclusion === 'success') return { state: 'green', run: latest };
   if (RED.has(latest.conclusion)) return { state: 'red', run: latest };
-  return { state: 'unknown', why: 'latest completed CI run has no success or red conclusion', run: latest };
+  return { ...unknown('latest completed CI run has no success or red conclusion'), run: latest };
 }
 
 /** Only a complete starci/ci-override@1 record for this exact commit can excuse a red run. */

package/release/gate.mjs

@@ -1,4 +1,4 @@
-// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and ONLY when every one is green it
+// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and when all required gates pass it
 // writes the L4 record <git-common-dir>/starci-release/<HEAD sha>.l4.json (head, tag, per-gate log path and sha256) and creates the annotated tag.
 // The canon pre-push hook lets main and v* tags through only for a HEAD with that tag and that record. Nothing is pushed here (see push.mjs).
 // The gate list comes from the optional `release:` block of .starcistacks/application-stacks.yaml, else from the app's managed package scripts.
@@ -13,6 +13,7 @@ import { failure, refusal } from '../stack/errors.mjs';
 import { latestDefaultBranchCi, requireGreenCi } from './ci-red.mjs';
 
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
+const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
 
 const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
 const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
@@ -63,14 +64,15 @@ function auditGate(audit) {
 
 /** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
 function sonarGate(services, env) {
-  const sonar = services?.sonar;
+  const configured = services?.sonar;
+  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
   const tokenName = sonar?.token;
   if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
   const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
   const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
   if (organization) command.push(`-Dsonar.organization=${organization}`);
   if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
-  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] } };
+  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar };
 }
 
 function gateProblems(entry, at, seen) {
@@ -209,6 +211,32 @@ export function launch(argv, platform) {
   return [argv[0], argv.slice(1)];
 }
 
+/** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. */
+async function sonarAvailability(ctx, gate) {
+  const sonar = gate.provider;
+  if (!sonar) return null;
+  let up = false;
+  try {
+    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
+    up = response.ok && (await response.json()).status === 'UP';
+  } catch { up = false; }
+  if (up) return null;
+  const detail = sonar.optional
+    ? `notice: sonar skipped: ${sonar.host} not reachable (services.sonar.optional)`
+    : `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds`;
+  return { skipped: sonar.optional === true, pass: false, detail };
+}
+
+/** Unreachable optional providers remain explicit skipped rows, with a real log and no scan invocation. */
+async function runAvailableGate(ctx, gate, options) {
+  const availability = await sonarAvailability(ctx, gate);
+  if (!availability) return runGate(ctx, gate, options);
+  const log = path.join(options.dir, `${gate.name}.log`);
+  fs.writeFileSync(log, availability.detail + '\n');
+  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
+    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+}
+
 function runGate(ctx, gate, { dir, platform }) {
   const log = path.join(dir, `${gate.name}.log`);
   const started = ctx.now();
@@ -270,7 +298,7 @@ function inspect(ctx, config, options) {
 }
 
 function planLines(config, facts, dir, recordPath) {
-  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (all must pass, in this order):'];
+  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (required gates must pass, optional provider outages are skipped, in this order):'];
   for (const gate of config.gates) {
     const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
     out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}`);
@@ -289,28 +317,31 @@ function assertUnmoved(ctx, head) {
 function writeRecord(ctx, { head, tag, results, recordPath }) {
   const record = {
     schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
-    note: 'The full gates ran on a clean HEAD; every entry links the real log and its sha256.',
+    note: 'Required gates passed on a clean HEAD; optional provider skips are explicit and every entry links its log and sha256.',
     gates: results,
   };
   fs.mkdirSync(path.dirname(recordPath), { recursive: true });
   fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
 }
 
-function runAll(ctx, config, { dir, platform }) {
-  fs.mkdirSync(dir, { recursive: true });
-  const results = [];
-  for (const gate of config.gates) {
-    const result = runGate(ctx, gate, { dir, platform });
-    results.push(result);
-    if (!result.pass) break;
-  }
-  return results;
+/** Gates run sequentially because each failure prevents subsequent commands and record creation. */
+async function runAll(ctx, config, options) {
+  fs.mkdirSync(options.dir, { recursive: true });
+  return config.gates.reduce(async (pending, gate) => {
+    const results = await pending;
+    if (results.some((result) => !result.pass && !result.skipped)) return results;
+    return [...results, await runAvailableGate(ctx, gate, options)];
+  }, Promise.resolve([]));
 }
 
-const summaryOf = (result) => `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+function summaryOf(result) {
+  let status = result.pass ? 'PASS' : 'FAIL';
+  if (result.skipped) status = 'SKIPPED';
+  return `${status} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+}
 
 /**
- * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if all are green,
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
  * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
  */
 export async function releaseGate(ctx, config, options = {}) {
@@ -325,14 +356,14 @@ export async function releaseGate(ctx, config, options = {}) {
   const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ci: { state: ci.state, notices: ciLines } };
   if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
   if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
-  const results = runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
+  const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
   const report = results.map(summaryOf);
-  const failed = results.filter((result) => !result.pass);
+  const failed = results.filter((result) => !result.pass && !result.skipped);
   if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
   assertUnmoved(ctx, facts.head);
   writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath });
   const created = facts.chosen.state !== 'on-head';
-  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: gates green on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
+  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
   const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;
   return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
 }

package/release/push.mjs

@@ -14,7 +14,7 @@ function readRecord(file) {
 }
 
 const greenRecord = (record, head, tag) => record?.head === head && record?.tag === tag
-  && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true);
+  && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true || (gate?.name === 'sonar' && gate?.skipped === true));
 
 /** The release gate as the hook reads it: the annotated tag on HEAD whose L4 record names head and tag. Returns { tag } or { reason }. */
 function gateState(ctx, head, prefix) {

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.2
+    version: 3.4.4
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.2
+    version: 8.4.4
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.0
+    version: 2.3.1
     group: starci
     install: registry
     side: be
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.5.0
+    version: 1.6.0
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.5.0
+    version: 4.6.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/sonar-gate.yaml

@@ -41,8 +41,8 @@ newCode:
     minReviewedPercent: 100
     unreviewedMax: 0
 # The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app lint`
-# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry), which writes ONE file, reports/lint.sonar.json
-# (`starci app lint --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry). CI runs it per side with --side and --sonar,
+# then merges rules by id and joins issues into ONE file, reports/lint.sonar.json, named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
 # the whole project at zero. The file carries three engines:
 #   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
 #   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -149,6 +149,16 @@ $defs:
       target: {type: number, minimum: 0, maximum: 100}
       components: {enum: [auto]}
       required: {type: boolean}
+      optional:
+        description: Skip an unreachable quality provider with a notice; SonarQube defaults true, SonarCloud and Codecov false.
+        type: boolean
+      badgeToken:
+        description: >-
+          codecov and sonar only: a read-only, public-safe badge token (Codecov graphing token, Sonar project badge token)
+          that the README badge of a private repository needs. It is public configuration rendered into README.md, never a
+          secret; a CI token or any write credential never goes here.
+        type: string
+        pattern: '^[A-Za-z0-9_-]{6,128}$'
       ecosystems: {type: array, items: {enum: [npm, docker, github-actions]}}
       schedule:
         type: object
@@ -272,6 +282,9 @@ $defs:
           repository: {type: string, pattern: '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$'}
           defaultBranch: {type: string, minLength: 1, default: main}
           workflow: {type: string, pattern: '^[A-Za-z0-9_.-]+\.ya?ml$', default: ci.yml}
+          visibility:
+            description: The GitHub repository visibility; private READMEs need services.<id>.badgeToken for live badges. Omitted means unknown.
+            enum: [public, private]
       secrets: {type: array, items: {$ref: '#/$defs/ciSecret'}}
       vars: {type: array, items: {$ref: '#/$defs/ciVariable'}}
       dependabot:
@@ -307,6 +320,9 @@ $defs:
           purpose: {type: string}
           optional: {type: boolean}
   ciVariable:
+    description: >-
+      A public CI variable either carries its literal value, or declares ownerValue true (no value) when only the owner
+      may supply it; var sync skips an owner-supplied value and ci verify checks that it exists by name.
     anyOf:
       - type: object
         additionalProperties: false
@@ -327,6 +343,25 @@ $defs:
           value: {type: string}
           purpose: {type: string}
           optional: {type: boolean}
+      - type: object
+        additionalProperties: false
+        required: [name, scope, ownerValue]
+        properties:
+          name: {$ref: '#/$defs/ciName'}
+          scope: {const: repository}
+          ownerValue: {const: true}
+          purpose: {type: string}
+          optional: {type: boolean}
+      - type: object
+        additionalProperties: false
+        required: [name, scope, ownerValue, environment]
+        properties:
+          name: {$ref: '#/$defs/ciName'}
+          scope: {const: environment}
+          environment: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+          ownerValue: {const: true}
+          purpose: {type: string}
+          optional: {type: boolean}
   serviceStack:
     description: >-
       Which stack defines a local service - either a project-owned .starcistacks stack

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "d230745d3aa5cfe65f75cb5fb2872924b935f1b4610c0b72db2f729572386404",
+  "hash": "93fd9007c93fe7430043d8b6682fd46dd0e1d5f9f9b7094fc94ffad2ccdcceeb",
   "global": [
     {
       "name": "json",
@@ -224,12 +224,12 @@ export const CATALOG = {
             {
               "name": "value",
               "type": "string",
-              "summary": "public variable value that must agree with the manifest"
+              "summary": "public variable value that must agree with the manifest; var set ownerValue requires stdin instead"
             },
             {
               "name": "execute",
               "type": "boolean",
-              "summary": "apply the variable sync plan"
+              "summary": "apply the variable sync plan; var sync skips ownerValue variables"
             },
             {
               "name": "json",
@@ -7317,12 +7317,12 @@ export const CATALOG = {
             {
               "name": "dev",
               "type": "boolean",
-              "summary": "save the packages as development dependencies"
+              "summary": "save the CLI and explicit packages as development dependencies"
             },
             {
               "name": "canon",
               "type": "boolean",
-              "summary": "install the target CLI and all of its exact StarCi canon pins"
+              "summary": "install the target CLI and move its declared exact StarCi canon pins"
             }
           ],
           "exit": {
@@ -7353,10 +7353,12 @@ export const CATALOG = {
             "bare package names resolve only from knowledge/hfs/canon-pins.yaml and never through a registry lookup",
             "explicit versions use exact x.y.z form and must agree with the canon pin when one exists, except the target CLI version on a canon upgrade",
             "naming @starci/cli or passing --canon installs the exact target CLI first,",
-            "then reads its installed HFS runtime canon-pins.yaml and installs every pinned @starci package in the same host lock",
+            "then reads its installed HFS runtime canon-pins.yaml and, in the same host lock,",
+            "moves each other pinned @starci package only where a root or workspace package.json declares it, in its own section",
             "--canon without a CLI positional uses the running runtime's exact CLI pin as the target",
             "target pins never fall back to the running runtime when the target pin file is missing or inconsistent",
-            "each target StarCi pin is reported as moved or refused with a reason; a failed canon phase exits nonzero even when the first CLI install succeeded",
+            "each target StarCi pin is reported as moved (with its workspace), skipped when no package.json declares it, or refused with a reason",
+            "a failed canon phase exits nonzero even when the first CLI install succeeded",
             "installs always use --save-exact and report the package.json and package-lock.json diff stat"
           ],
           "runtimeSide": "host"

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -4,6 +4,14 @@ import { parseYaml } from '../../engine/yaml.mjs';
 
 const nameOf = (item) => typeof item === 'string' ? item : item?.name;
 
+/** A public CI variable declares either a manifest value or an owner-supplied value, never both. */
+function variableProblems(item, at, invalid) {
+  const hasValue = item != null && Object.hasOwn(item, 'value');
+  const hasOwnerValue = item != null && Object.hasOwn(item, 'ownerValue');
+  if (hasValue && hasOwnerValue) invalid(at, 'a variable has either a value or ownerValue');
+  else if (!hasValue && item?.ownerValue !== true) invalid(at, 'a variable needs a value or ownerValue: true');
+}
+
 /** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
 export function readCiDeclaration(doc) {
   const problems = [], seen = new Set();
@@ -17,8 +25,9 @@ export function readCiDeclaration(doc) {
     if (!['repository', 'environment'].includes(scope)) invalid(`${where}.scope`, 'scope must be repository or environment');
     if (scope === 'environment' && (typeof item?.environment !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.environment))) invalid(`${where}.environment`, 'environment scope requires an environment name');
     if ((dependabot || scope !== 'environment') && item && Object.hasOwn(item, 'environment')) invalid(`${where}.environment`, 'only environment scope may name an environment');
+    if (variable) variableProblems(item, where, invalid);
     return { name, scope, environment: item?.environment ?? null, purpose: item?.purpose ?? null,
-      optional: item?.optional === true, ...(variable ? { value: item?.value } : {}) };
+      optional: item?.optional === true, ...(variable ? { value: item?.value, ownerValue: item?.ownerValue === true } : {}) };
   });
   const ci = doc?.ci;
   const secrets = normalize(ci?.secrets, 'ci.secrets');
@@ -33,13 +42,13 @@ export function qualityServices(doc, { example = false } = {}) {
   const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
   return {
     sonar: !sonar || sonar.mode === 'disabled' ? null : {
-      provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
+      provider: sonar.provider, mode: sonar.mode, optional: sonar.optional ?? sonar.provider === 'sonarqube', host: sonar.host?.public || sonar.host?.local || null,
       organization: sonar.organization ?? null,
       organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
       qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
       token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
     },
-    codecov: { enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
+    codecov: { optional: codecov.optional ?? false, enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
       flag: codecov.flag ?? null, target: codecov.target ?? 100, components: codecov.components ?? 'auto', required: codecov.required ?? true, wiring: codecov.ci?.wiring ?? 'required' },
     dependabot: { ecosystems: [...(dependabot.ecosystems ?? ['npm', 'github-actions', 'docker'])],
       schedule: { interval: 'weekly', ...dependabot.schedule }, groups: { minorPatch: 'grouped', major: 'per-package', ...dependabot.groups },